<!--
 Copyright 2010 Andrew Rickmann

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->
<?php include('header.php'); ?>
<div id="content" class="prepend-top last">
    <div id="main-content" class="prepend-top span-18">
    <h1>Adding new request rules</h1>
    <p>A request rule is how Waterwheel determines what content to display when the user enters a URL.</p>
    <p>Each rule is made up of:</p>
    <ul>
	<li>A name;</li>
	<li>A function callback;</li>
	<li>The URL replacement string; and</li>
	<li>An optional description</li>
    </ul>
    <p>When the user requests a particlar URL that URL will be compared to each of the request rules' replacement strings. When a rule matches the URL structure the callback function specified in the rule will be called and that function will determine which data should be gathered from the database and which content should be returned to the browser.</p>
    <p>The URL replacement string contains either plain text or placeholders for certain types of data.</p>
    <h2>Adding a new rule</h2>
    <p>To add a new rule your plugin should use the <em>request_rules</em> action. This is triggered just before the request rules check the URL.</p>
    <p>This action passes the request object which contains the <code>add_request_rule</code> and <code>remove_request_rule</code> methods.</p>
    <p>The example below that shows a plugin using the <em>request_rules</em> action, and <code>add_request_rule</code> method to add a new rule that will handle
    URLs in the format {yoursite}/example/{slug}.</p>
    <?php

    //insert the code content from the sample file.
    $sample_file_content = file_get_contents( APPLICATION_PATH . '/plugins/gettingstarted/files/samples/requestrulesample.txt'  );
    $geshi->set_source($sample_file_content);
    echo $geshi->parse_code();
    
    ?>
    <p><a href="<?php echo APPLICATION_PATH; ?>/plugins/gettingstarted/files/samples/requestrulesample.txt">Download a copy of the sample plugin.</a></p>
    <h3>Notes</h3>
    <p>The name can be anything as long as it is unique. If you create a rule with the same name as an existing rule it will override the existing rule.</p>
    <p>The function callback should point to a function in the plugin that will take the URL and then figure out what to do with it.</p>
    <h3>Formatting the replacement string</h3>
    <p>The replacement string is the URL you want to match, but using either plain text, or placeholders, to describe the data.</p>
    <p>So, for example, if you want to match URLS that begin with 'example' you can simply type 'example'. It is important to note however that you must specify content or a placeholder for every single part of the URL or the URL will not match. So 'example' will not math a url or 'example/sommat'. If you want to capture the second part you can use a data placeholder, as per the example above. 'example/{data:varname}' would match the URL 'example/sommat' and would pass the value 'sommat' to the request_params variable under the name 'varname'.</p>
    <p>When placeholders are used, the data that matches that placeholder is added to the request_params variable so that you can access it within the request handler.</p>
    <p>The following table contains the placeholders that can be used:</p>
    <table>
	<thead>
	    <tr>
		<th>Placeholder</th>
		<th>Use</th>
	    </tr>
	</thead>
	<tbody>
	    <tr>
		<td>{content-type}</td>
		<td>Matches the type slug of any current content-type.</td>
	    </tr>
	    <tr>
		<td>{content-type:[type_slug]}</td>
		<td>This will match in the same way as simply including the type_slug in plain text, but this method will populate</td>
	    </tr>
	    <tr>
		<td>{date}</td>
		<td>Matches a year (2009), a year and a month (2009/12), or a year and a month and a day (2009/12/24).</td>
	    </tr>
	    <tr>
		<td>{year}</td>
		<td>Matches a year only. If you want more control than than {date} provides.</td>
	    </tr>
	    <tr>
		<td>{month}</td>
		<td>Matches a numeric month only. If you want more control than {date} provides.</td>
	    </tr>
	    <tr>
		<td>{day}</td>
		<td>Matches a numeric day only. If you want more control than {date} provides.</td>
	    </tr>
	</tbody>
    </table>
    <h2>Adding new placeholders</h2>
    <p>When each URL is run placeholders are replaced by part of a regular expression. So, for example, {slug} is replaced with '[a-z]{1,1}[a-z0-9\-]*'. </p>
    <p>To add a new placeholder you must use the filter 'request_rules_regex' which will pass an array of the current placeholders and add your new placeholder to that array.</p>
    <h3>Note on permalinks</h3>
    <p>The same process works in reverse to produce permalinks. So, if you add a new placeholder you will also need to include some code to convert this placeholder back into a URL. See <strong style="color:red">"XXXXXXXXXXX</strong> for details.</p>
    </div>
    <?php include('plugintopics.php'); ?>
</div>
<?php include('footer.php'); ?>

